---
title: Insert letter request
summary: Creates a pending letter-request record via a stored procedure and returns the generated sequence number, used by the DEF-letter and recon-request-letter workflows.
status: draft
owner: SAIF Documentation Pipeline
last_reviewed: 2026-08-21
library: SAIF.Application.Claim.Legal
reference_type: embedded
operation_id: OP-LGL-002
trigger: Called by Print DEF letter or Save hearing request/update case (recon request)
---

# Insert letter request

This shared, base-class operation builds and executes a stored-procedure call to insert a pending letter-request record for a legal case and returns the generated request sequence number. It is a support operation called by [Print DEF letter](print-def-letter.md) and [Save hearing request / update case](save-hearing-request-update-case.md).

| Field | Value |
| --- | --- |
| **Operation ID** | OP-LGL-002 |
| **Trigger** | Called by `clsScheduleManager.PrintDEF` (DEF letter) or `clsRequestManager.OnWrite` (recon-request letter, `SendReconRequest`) |
| **Inputs** | `letterTypeCode` (5 chars), legal case number, claim ID, hold date, create user |
| **Outputs** | `requestNum` — generated letter-request sequence number |
| **Primary components** | `LegalManagerBase.insertLetterRequest` |
| **Entry point** | `SAIF.Application.Claim.Legal\LegalManagerBase.vb` |

## Steps

1. Build an `IDataRequest` with `CommandType = StoredProcedure` and `SQLStatement = "pk80001_LEGALNET.insertLetterRequest"` ([SQL-001](../sql/SQL-001-insert-letter-request.md)).
2. Bind parameters onto the request:
   - `letterTypeCode` (5 characters)
   - `aLegalCaseNum`
   - `holdDate` — nullable date; sent as `DbType.Date` (NULL) when the caller passes `Date.MinValue`, otherwise the actual date value
   - `createUser` (30 characters)
   - `aClaimId`
   - `requestNum` — bound as an `InputOutput` parameter
3. Execute the request via `DPI.DataAccessLayer.ProcessPortalRequest` ([SQL-001](../sql/SQL-001-insert-letter-request.md)).
   - On failure: the underlying data-access exception propagates to the caller (no local catch in this operation).
4. Read the output `requestNum` parameter from the completed portal request and return it as the generated letter-request sequence number.

## Process flow

The following diagram visualizes this operation's control flow.

```mermaid
flowchart TD
	Start([Caller supplies letter type/case/claim/hold date]) --> Build[Build IDataRequest<br>StoredProcedure call]
	Build --> Bind[Bind parameters<br>via insertLetterRequest]
	Bind --> Exec[ProcessPortalRequest]
	Exec --> Read[Read requestNum output parameter]
	Read --> EndOk([Return requestNum])
```

## Failure and edge-case behavior

- `holdDate = Date.MinValue`: sent to Oracle as a NULL date rather than a literal minimum-date value.
- Data-access failure during `ProcessPortalRequest`: propagates unhandled to the calling operation ([Print DEF letter](print-def-letter.md) or [Save hearing request / update case](save-hearing-request-update-case.md)).

## Related documentation
- [Operations and processes](../operations-processes.md)
- [Business rules](../business-rules.md)
- [SQL catalog](../sql/index.md)
- [Database tables](../database-tables.md)

## Sources
- `SAIF.Application.Claim.Legal\LegalManagerBase.vb`